Introduction

Authentication mechanisms provide the core functionality to validate users credentials and authenticate them against a preconfigured Identity Store. They define the rules about security information, such as the format of how security information is stored in both credentials and tokens.

Each mechanism knows how to handle a specific org.picketbox.core.UserCredential type, from which all the necessary information will retrieved to proceed with the user authentication. During the authentication, the mechanisms are able to query the Identity Manager in order to retrieve and check the information for a specific user. In other words, check if the user is stored at a preconfigured Identity Store, validate his credentials and so forth.

Examples of mechanisms are username and password authentication, TOTP(Time-based One-time Password), certificate, digest, etc. 

Overall Design

The contract for authentication mechanisms is defined by the org.picketbox.core.authentication.AuthenticationMechanism interface.

This interface defines some important methods as follow:

• boolean supports(UserCredential credential);
  This is a callback method invoked during the authentication process to know if the a specific credential type is supported by the mechanism.

• List<AuthenticationInfo> getAuthenticationInfo();
  This method returns a list of org.picketbox.core.authentication.AuthenticationInfo. This class holds the information about the mechanism like which credentials type are supported, some description, etc. In other words, this method allows to described a specific mechanism.

• AuthenticationResult authenticate(UserCredential credential);
  This is the most important method when talking about authentication. The implementation defines the authentication logic and how the mechanism will handle the supported credentials to perform it.
  You may noticed that this method returns a org.picketbox.core.authentication.AuthenticationResult type. This is the outcome for the authentication process, providing useful information like the authentication status, the user Principal, messages, etc.

The diagram bellow gives a overall sight about how the mechanisms are used during the authentication.

Basically, the authentication takes a few steps:

1. The PicketBoxManager receives a authentication request for a specific UserContext instance. This instance is already setup with a UserCredential.

2. The manager retrieves all supported/registered authentication mechanisms. For each mechanisms, the manager checks if the provided UserCredential type is supported.

3. If the mechanism supports a specific credential type it tries to validate it and return a AuthenticationResult instace populated with the user principal, authentication status, messages, etc. At this point the Identity Manager is used to query user information, validate credentials, etc.

4. The PicketBoxManager uses the result to continue (or not) with the user authentication.

public class UserNamePasswordAuthenticationMechanism extends AbstractAuthenticationMechanism {

    @Override
    public List<AuthenticationInfo> getAuthenticationInfo() {
        List<AuthenticationInfo> arrayList = new ArrayList<AuthenticationInfo>();

        arrayList.add(new AuthenticationInfo("Username and Password authentication service.",
                "A simple authentication service using a username and password as credentials.",
                UsernamePasswordCredential.class));

        return arrayList;
    }

    @Override
    protected Principal doAuthenticate(UserCredential credential, AuthenticationResult result) throws AuthenticationException {
        UsernamePasswordCredential userCredential = (UsernamePasswordCredential) credential;


        // try to retrieve the user from the configured identity store
        User user = getIdentityManager().getUser(userCredential.getUserName());

        if (user != null && getIdentityManager().validateCredential(user, userCredential.getCredential())) {
            return new PicketBoxPrincipal(user.getId());
        }

        return null;
    }
}

Configuration

PicketBox already provides some built-in implementations. That means you don't need to provide any additional configuration if you are going to use one of these built-in mechanisms.

But if you want to provide your own authentication mechanism implementation you just need to build PicketBox configuration as following:

ConfigurationBuilder builder = new ConfigurationBuilder();

CustomAuthenticationMechanism customMechanism = new CustomAuthenticationMechanism();

// register the custom authentication mechanism
builder.authentication().mechanism(customMechanism);

// build the configuration and create/start the manager

Bulit-in Implementations